* Ruby - Scaffold Gem

A gem scaffolding script with basic security in mind.

Version: 0.4.0

/Scaffold currently tested, and used, successfully on macOS. According to/
/CI there is a bug in the script. Unfortunately, we couldn't reproduce it./

** Why?

Although there are a few options for scaffolding gems, each focuses on
different aspects of gem production but security.

** Requirements

This script, as well as the resulting gem scaffold, require one of the
latest two Ruby releases; 2.5.X, or 2.6.X.

** Quick Start

*** Download

To use this scaffold

#+BEGIN_SRC shell
$ git clone https://notabug.org/rem/ruby-scaffold_gem.git <gem_dir>
#+END_SRC

If you prefer not to open an account on [[https:://notabug.org][NotABug.org]]

#+BEGIN_SRC shell
$ git clone git@notabug.org:rem/ruby-scaffold_gem.git <gem_dir>
#+END_SRC

You can even get it via [[https://notabug.org/tor][tor]]

*** Usage

The scaffold is meant to be run from the command line. It requires some
basic info:

- namespace.
- author.
- email
- repo.
- license.

#+BEGIN_SRC shell
$ cd <gem_dir>
$ ruby scaffold_gem.rb -n SomeGem -b -a me -e me@email.com -r https://example.com -l ISC
#+END_SRC

The supported namespace format is camel cased (~SomeGem~). It supports a
scoped namespace for plugins according to [[https://guides.rubygems.org/name-your-gem/][RubyGems conventions]]
(~SomeGem::SomePlugin~). Since the convention is only at the namespace
level, and not on the type of container (~class~ or ~module~), this
scaffold generates ~class SomeGem~ containing ~module SomePlugin~.

As for the other options, ~author~ refers to the person starting the gem.
~email~ to the maintainers' emails. ~repo~ points to where the gem's code
is hosted. ~license~ the type of license to use for the gem. Rubygems
expects a license short identifier based on the [[https://spdx.org/licenses/][SPDX license list]].

The scaffold includes a copy of ISC license for convenience only. You can
use whichever license you want on your gem.

To list all options run

#+BEGIN_SRC shell
$ ruby scaffold_gem.rb --help
#+END_SRC


** Review

Once the scaffold is generated change ~/lib/<gem_name>/doc.rb~'s
summary and description. The current ones are set simply to pass the
tests.

Chances are that running the tests for the first time, will raise
warnings due to mismatched indentation, but no actual failures.
Indentation issues won't get fix, that's the code editor's job.

Make sure to skim all the files. This is merely a scaffold, and some
useful stuff might had to be commented-out to pass all tests.

*** Contents at a glance

A ~Manifest.md~ with all the files included in the gem package. Meant to
be edited by hand. A test case fails when the ~Manifest.md~ contents
don't match those of the ~lib~, and ~bin~ directories.

Although it doesn't assume a particular git web service; it does take
advantage of gitlab's continuous integration. The test suite is run under
Linux using Ruby's de facto distro, and Alpine.

It includes a few development tasks from code metrics to building the
documentation. The list of development dependencies included can be found
at the bottom of the ~_gem_name.gemspec.erb~ file.

The scaffold itself includes tests checking the completeness of the
documentation. Although an incomplete documentation won't fail the CI run
by default it publishes the documentation using Gitlab pages.

Gem releases are not automated on the CI script to prevent leaking
credentials to the pipeline logs.

The ~gemspec~'s details, other than the dependencies, have been extracted
to help prevent unplanned changes. The relevant files are in
~lib/<gem_name>/~ as ~doc.rb~, ~manifest.rb~, and ~version.rb~.

On the generated scaffold, we can run the test suite in full using
~bundle exec rake~. For development, though, use ~./dev/autotest~ to keep
the tests on running. Use =C-c= (=SIGINT=) twice to stop =autotest=.


** License

Copyright (c) 2018-2019, René Maya.

Permission to use, copy, modify, and distribute this software for any
purpose with or without fee is hereby granted, provided that the above
copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
